package com.example.rssreader.service;

import com.example.rssreader.entity.Article;
import com.example.rssreader.entity.RssFeed;

import java.util.List;

/**
 * RSS解析服务接口
 * 定义RSS源解析和文章抓取相关的操作
 * 
 * @author RSS Reader Team
 * @version 1.0.0
 * @since 2024-01-01
 */
public interface RssParserService {

    /**
     * 解析RSS源信息
     * 从RSS URL获取基本信息（标题、描述等）
     * 
     * @param url RSS源URL
     * @return RSS源实体，包含解析出的基本信息
     * @throws RuntimeException 当URL无效或解析失败时抛出异常
     */
    RssFeed parseFeedInfo(String url);

    /**
     * 解析RSS源的文章列表
     * 从RSS URL获取最新的文章列表
     * 
     * @param feed RSS源实体
     * @return 文章列表
     * @throws RuntimeException 当解析失败时抛出异常
     */
    List<Article> parseArticles(RssFeed feed);

    /**
     * 验证RSS URL是否有效
     * 检查URL是否可访问且为有效的RSS格式
     * 
     * @param url RSS源URL
     * @return true-有效，false-无效
     */
    boolean validateRssUrl(String url);

    /**
     * 获取RSS源的最新更新时间
     * 从RSS源中解析最后更新时间
     * 
     * @param url RSS源URL
     * @return 最新更新时间字符串，解析失败时返回null
     */
    String getLastBuildDate(String url);

    /**
     * 测试RSS源连接
     * 检查RSS源是否可正常访问
     * 
     * @param url RSS源URL
     * @return 连接测试结果信息
     */
    String testConnection(String url);

    /**
     * 解析单个RSS条目为文章实体
     * 内部方法，用于将RSS条目转换为Article对象
     * 
     * @param entry  RSS条目
     * @param feedId RSS源ID
     * @return 文章实体
     */
    Article parseEntry(Object entry, Long feedId);

    /**
     * 清理HTML标签
     * 从文章内容中移除HTML标签，保留纯文本
     * 
     * @param htmlContent HTML内容
     * @return 纯文本内容
     */
    String cleanHtmlContent(String htmlContent);

    /**
     * 截取文章摘要
     * 从文章内容中提取指定长度的摘要
     * 
     * @param content 文章内容
     * @param maxLength 最大长度
     * @return 文章摘要
     */
    String extractSummary(String content, int maxLength);

    /**
     * 批量解析多个RSS源
     * 用于定时同步任务
     * 
     * @param feeds RSS源列表
     * @return 解析结果统计信息
     */
    String batchParseFeeds(List<RssFeed> feeds);
}